// Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of dart.core;

/**
 * 字符串中的基本搜索接口。
 */
abstract class Pattern {
  // NOTE: When using "start" index from the language library, call
  // without an argument if start is zero. This allows backwards compatiblity
  // with implementations of the older interface that didn't have the start
  // index argument.
  /**
   * 针对字符串，反复匹配此Pattern。
   *
   * 如果设置了[start]参数，匹配会从索引处开始。
   *
   * 返回的Iterable会从索引处开始，惰性计算字符串中所有Pattern的非重叠匹配。
   * 如果仅仅需要第一次匹配，不应该使用此方法计算所有可能的匹配。
   *
   * 方法通过反复查找字符串中Pattern的第一次匹配，来查找所有Match。
   * 并且，它是从之前匹配的末尾开始（初始化为0）。
   *
   * 如果模式在某个点匹配到空字符串，
   * 下一个匹配会从之前匹配的末尾加1开始查找。
   */
  Iterable<Match> allMatches(String string, [int start = 0]);

  /**
   * 针对开始的字符串匹配模式。
   *
   * 如果设置了[start]参数，它的范围必须在`0`和`string.length`之间。
   * 在这种情况下，模式会对字符串[start]位置进行测试。
   * 也就是说，从[start]开始，如果模式可以匹配字符串的一部分，返回[Match]。
   * 如果模式没有匹配到结果，返回`null`。
   */
  Match matchAsPrefix(String string, [int start = 0]);
}

/**
 * 在字符串中搜索的一个结果。
 *
 * Match对象的Match或[Iterable]由[Pattern]的匹配方法返回。
 *
 * 下面的例子是查找所有[RegExp]在[String]的匹配，并迭代Match对象返回的可迭代对象。
 *
 *     RegExp exp = new RegExp(r"(\w+)");
 *     String str = "Parse my string";
 *     Iterable<Match> matches = exp.allMatches(str);
 *     for (Match m in matches) {
 *       String match = m.group(0);
 *       print(match);
 *     }
 *
 * 这个例子的输出是：
 *
 *     Parse
 *     my
 *     string
 *
 * 一些模式，特别是正则表达式，可能记录的子字符串只是匹配的一部分
 * （通过调用Match对象的_groups_方法获取）。
 * 并且，部分模式可能不会有任何的group，它们的匹配[groupCount]始终为0。
 */
abstract class Match {
  /**
   * 返回匹配开始时的索引位置。
   */
  int get start;

  /**
   * 返回匹配最后一个字符之后的索引位置。
   */
  int get end;

  /**
   * 返回指定[group]的字符串匹配。
   *
   * 如果[group]是0，返回Pattern的匹配。
   *
   * 如果模式没有分配值作为匹配的一部分，结果可能是`null`。
   */
  String group(int group);

  /**
   * 返回指定[group]的字符串匹配。
   *
   * 如果[group]是0，返回Pattern的匹配。
   *
   * [Match.group]的短别名。
   */
  String operator [](int group);

  /**
   * 返回一个List，包含指定索引的group。
   *
   * List包含的字符串，
   * 是使用[groupIndices]中的每个索引，调用[group]的返回值。
   */
  List<String> groups(List<int> groupIndices);

  /**
   * 返回匹配中捕获到的group数量。
   *
   * 一些模式可能捕获input的部分，用于计算完整的匹配。
   * 这也是[group]方法允许的最大参数。
   */
  int get groupCount;

  /**
   * 用于计算匹配的原始字符串。
   */
  String get input;

  /**
   * 用于在[input]中进行搜索的模式。
   */
  Pattern get pattern;
}
